<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html lang="en">
<head>
<meta name="copyright"
	content="Copyright (c) 2022 IBM Corporation and others. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1"
	type="text/css">
<title>Adopting 4.26 mechanisms and APIs</title>
</head>
<body>
	<h1>Adopting 4.26 mechanisms and APIs</h1>
	
	<p>This section describes changes that are required if you are
		trying to change your 4.25 plug-in to adopt the 4.26 mechanisms and
		APIs.</p>

	<h2>JobManager implementation changes: Possible deadlock in IJobChangeListener</h2>
<p>Attention: The JobManager implementation was changed! The old
JobMangager implementation notified IJobChangeListener about various
IJobChangeEvent without strict order in various threads. For example
scheduled() was called in a thread that did call schedule() on a job
while done() was normally called within a worker thread. In case of a
repeated schedule() both notifications could run in parallel. That was a
race condition. The listener could not deterministically know if the job
was still scheduled or already done. As a consequence a join() could
have returned too early or the Progress View did not show jobs that did
still run. And probably many other things went wrong totally unnoticed.
Even multiple notifications could have happened in parallel in various
worker threads, as there is no guarantee that the next execution is done
in the same worker.</p>
<p>To fix this indeterministic behavior all events for the same Job instance will
now be sent one after the other. It is still not defined in which thread
job events will be sent, but the new implementation will not call any
IJobChangeListener until all pending events for the same job instance are processed
by all registered IJobChangeListener. The new implementation will also
wait with any job state change until all calls to IJobChangeListener for
that job returned.</p>
<p>The IJobChangeListener javadoc clearly specifies "whether the state
change occurs before, during, or after listeners are notified is
unspecified." - and the implementation changed within that broad
specification. Unfortunately some IJobChangeListener around rely on the
old implementation. They may now deadlock. For example the following
snippet can now deadlock:</p>
<pre><code> job.schedule(); // may result in done();
 synchronized (lock){
  boolean schedule = ...; // lock needed for reasons
  if (schedule ) job.schedule(); // schedule() will notify scheduled()
  // - which may not return before previous Notifications return!
 }

 public void done(IJobChangeEvent event) {
  // can not enter while other Thread holds lock:
  synchronized (lock) {// possible deadlock
  }
 }
</code></pre><p>Instead use:</p>
<pre><code> job.schedule();
 boolean schedule;
 synchronized (lock) {
  schedule=...; // lock needed for reasons
 }
 if (schedule) job.schedule();

 public void done(IJobChangeEvent event) {
  synchronized (lock) {// OK
  }
 }
</code></pre><p>The same problem may occur on all IJobChangeListener methods and all
methods that result in IJobChangeEvent being sent: Job.schedule(),
cancel(), wakeUp(), sleep() and JobManager shutdown. Make sure all
IJobChangeListener implementations do not block and return promptly.</p>
<p>Due to the extreme risk the new implementation tries to identify
non-conforming IJobChangeListener and do a fall back: when an
IJobChangeEvent is not handled within 3 seconds a timeout error is
logged with stacktraces of the competing threads and the JobManager will
no longer wait - until JVM is restarted. Further calls to
IJobChangeListener may occur in non deterministic order and JobManager.join(family) can return
too soon. It is however possible, that there may also be some deadlocks in clients code due
to the changed JobManager implementation that may be undetected by
JobManager.</p> 
<p>Also note that it is undefined in which thread IJobChangeListener methods are called. 
Clients may have relied on the old implementation which called done() in the UI (SWT) thread for UIJob - but that is not the case anymore - it may happen in a background thread.</p>
<strong>It is recommended to check existing IJobChangeListener implementations for possible regressions if updating to the new target platform.</strong>
	
	<h2>Migration to SLF4J 1.7.36 from Maven-Central</h2>
      <p>
      The Eclipse Platform migrated to the SLF4J artifacts from Maven-Central in version 1.7.36.
      With this migration the <code>Bundle-SymbolicName</code> changed from <code>org.slf4j.api</code> to <code>slf4j.api</code>.
      </p>
      <p>
      Furthermore the way how a SLF4J-binding Plugin is wired to the slf4j-api Plugin has changed.
      Previously with the artifacts provided by Eclipse Orbit, each binding had a separate fragment whose host was the <code>org.slf4j.api</code> Plugin and that required the binding Plugin.
      The <code>slf4j.api</code> Plugin from Maven-Central instead imports the package <code>org.slf4j.impl</code>, which is exported by each binding Plugin.
      Consequently, unlike before, <code>slf4j.api</code> does not resolve if no binding is present.
      If you want to disable logging with slf4j, you can add the <code>slf4j-nop</code> binding to your application or product.
      </p>
      <p>
      Additionally the <code>slf4j.api</code> Plugin as well as <code>org.apache.commons.logging</code> have been removed from all Features of the Eclipse Platform to enable Application/Product builders to freely choose the logging-framework and bridging strategy eventually used in their product.
      If nothing is chosen explicitly P2 assembles a minimal result depending on the available Plugins.
      </p>
	
</body>
</html>
